DEFINITION MODULE Files;

(*
*    Copyright (c) 1985, 1986 by
*    Djavaheri Bros., Foster City, California.
*    All Rights Reserved.
*
*    This software is furnished under a license and may be used and copied
*    only  in accordance with  the  terms  of  such  license and  with the
*    inclusion of the above copyright notice.  This software or  any other
*    copies thereof may not be provided or otherwise made available to any
*    other  person.   No title to and ownership of the  software is  herby
*    transferred.
*
*    The information in this software is  subject to change without notice
*    and  should  not be construed as a commitment by Djavaheri Bros.   No
*    warranty is implied or expressed.
*
*   SCCID  = "1.2    9/19/86"; 
*)


(*									  
*	History of Modifcation						   
*	Date		Who	Reasone			 
*       01/09/86        K.Y.    Add IsAtty : BOOLEAN to the file descriptor

*)
FROM SYSTEM IMPORT ADDRESS;
FROM SYSTEMX IMPORT MERROR;

EXPORT QUALIFIED
    File,         FileDescriptor, FileState,	FilePosition,
    BinTextMode,  ReadWriteMode,  ReplaceMode,
    Open,         Create,         Close,        Remove,
    Reset,        Rewrite,        Truncate,     Flush,
    EOF,          State,          ResetState,   CloseAll,
    GetFileName,  StateSet,BuffSize,SetFileError, Lookup;

TYPE
    BinTextMode   = (binMode, textMode);
    ReadWriteMode = (readOnly, readWrite, appendOnly);
    ReplaceMode   = (noReplace, replace);

    FileState = (ok,
        atEol,            (* just read an EOL *)
        atEof,            (* just positioned at EOF *)
                          (* errors opening files *)
        nameError,        (* illegal syntax in file name as passed   *)
        noFile,           (* file with specified name not found      *)
        existingFile,     (* file already exists                     *)
                          (* errors opening or operating *)
        deviceError,      (* some hardware error during I/O          *)
        noMoreRoom,       (* no room on volume/medium/directory      *)
        accessError,      (* protect, read/write, binary/text error  *)
                          (* errors operating upon a file *)
        notOpen,          (* operation on unopened file              *)
        endError,         (* read attempted after EOL or EOF         *)
        outsideFile,      (* position before BOF or after EOF        *)
                          (* and *)
        otherError);      (* error unanticipated by this definition  *)

    StateSet = SET OF FileState;

    FilePosition = INTEGER;
    (*     WARNING!   THIS IS NOT OPAQUE, BUT SHOULD BE TREATED AS SUCH.
       Its contents are implementation-dependent, and should not be
       manipulated directly.  It is implemented as a RECORD, not a POINTER,
       so its contents may be written to/from other modules. It SHOULD be an 
       opaque type, but this compromise was made so that its contents could be
       recorded in files.
       *)

    File = POINTER TO FileDescriptor;

    FileDescriptor = RECORD
    (*     WARNING!   THIS IS NOT OPAQUE, BUT SHOULD BE TREATED AS SUCH. *)
			link       : File;	(* Files are kept in a list *)
			lun, rlun  : CARDINAL;	(* unit number for I/O *)
			BufferSize : CARDINAL;
			FileBuffer : ADDRESS;
		        ReadCount  : INTEGER;	 (* Buffer is read in *)
                        HighMark   : CARDINAL;
			position   : FilePosition;
			namelen    : CARDINAL;
			Name       : ARRAY [0..80] OF CHAR;
			State      : FileState;
			BinText    : BinTextMode;
			ReadWrite  : ReadWriteMode;
		        BufferEof  : BOOLEAN;	 (* Buffer is at eof *)
			Dirty      : BOOLEAN;	 (* Buffer is marked *)
                        IsAtty     : BOOLEAN;
		      END;

 VAR BuffSize:CARDINAL;

	
(* Lookup for a file. The user has 2 ways to use this routine :
   1. pass in signal = TRUE which means :
       If the file the user looks for is not found, then create a file with 
       the file name given.
   2. pass in signal = FALSE which means
       If the file the user looks for is not found , then do nothing - don't
       created a new file.
   The signal returns what this routine did :
       if the returned signal = TRUE,  it means a file is created or opened.
       if the returned signal = FALSE, it means a file is NOT created or opened.
  *)

PROCEDURE Lookup( VAR f : File;
                  VAR fileName : ARRAY OF CHAR;
                  VAR signal   : BOOLEAN);

PROCEDURE Open  (* Open an existing external file; error if not present *)

  ( VAR file      : File;
    VAR name      : ARRAY OF CHAR;
        binText   : BinTextMode;
        readWritemode : ReadWriteMode;
    VAR state     : FileState);

PROCEDURE Create (* Create a new external file. If named file already exists,
                    then overwrite only if overwriteMode = overwriteEnable,
                    otherwise, error *)

  ( VAR file      : File;
    VAR name      : ARRAY OF CHAR;
        binText   : BinTextMode;
        replace   : ReplaceMode;
    VAR state     : FileState);

PROCEDURE Close (* Close the file, saving the external file *)

  ( VAR file     : File;
    VAR state    : FileState);

PROCEDURE CloseAll(* Close all the open files, including SimpleIO *)
    (VAR state    : FileState);


PROCEDURE Remove (* Close the file, removing the external file *)

  ( VAR file     : File;
    VAR state    : FileState);

PROCEDURE Reset (* Reposition to the start of the file *)

  (     file      : File;
    VAR state     : FileState);

PROCEDURE Rewrite (* Reposition to start of file and then truncate file *)

  (     file      : File;
    VAR state     : FileState);

PROCEDURE Truncate (* Set the end of the file to the current position *)

  (     file      : File;
    VAR state     : FileState);

PROCEDURE Flush (* Writes any modified buffers to the storage medium *)

  (     file      : File;
    VAR state     : FileState);

PROCEDURE EOF (* Returns true if last operation was not performed.
                 (Value of true is caused by end of file or error    *)

  (     file      : File) : BOOLEAN;

PROCEDURE State (* Returns the current state of the file *)

  (    file      : File) : FileState;

PROCEDURE ResetState (* Allows continued operation in presence of error 
                        conditions; reevaluates EOF/EOL so that they 
                        really indicate file position.                   *)

  (     file      : File;
    VAR state     : FileState);

PROCEDURE GetFileName (* Return complete and unambiguous file name *)

  (     file     : File;
    VAR name     : ARRAY OF CHAR;
    VAR state    : FileState);

PROCEDURE SetFileError(VAR state: FileState; ErrorNumber:MERROR);

END Files.
